Split Jaguar1 into src/jaguar1/ + compile-time per-chip selection by josephnef · Pull Request #125 · OpenIPC/devourer

josephnef · 2026-07-01T16:33:27Z

What

Two-part refactor of the source tree:

Split src/jaguar1/ (commit 93b9756) — moves the Jaguar1 driver files into src/jaguar1/, mirroring the existing src/jaguar3/ layout, and decouples the two generations. Neither #includes the other; shared symbols (MGN_RATE, Packet/RX types, the TX-descriptor bit macros) moved to neutral src/RateDefinitions.h, src/RxPacket.h, src/TxDescBits.h. RtlUsbAdapter is now generation-agnostic (RX parse relocated into RtlJaguarDevice).
Compile-time per-chip selection (commit 562084b) — four CMake options, all default ON so a plain cmake -S . -B build is unchanged:

option chips

DEVOURER_JAGUAR1 8812AU / 8811AU / 8821AU

DEVOURER_8814 8814AU (requires DEVOURER_JAGUAR1)

DEVOURER_JAGUAR3_8822C 8812CU / 8822CU

DEVOURER_JAGUAR3_8822E 8812EU / 8822EU

Invalid combos (none selected; 8814 without jaguar1) fail configure with FATAL_ERROR. Each group exports a PUBLIC DEVOURER_HAVE_* define; every site that references a dropped group's symbols is guarded with #if defined(DEVOURER_HAVE_*). The factory returns nullptr (and logs) when a plugged chip's support isn't built; demos null-check and exit cleanly.

Size win

8812AU-only WiFiDriverDemo drops from 2.58 MB → 1.03 MB (−60%); 8822e-only is 0.84 MB.

CI

New build-configs matrix (jaguar1-only, jaguar1+8814, 8822c-only, 8822e-only, jaguar3-only) + reject-bad-configs (the two FATAL cases), so a missing guard — which only fails to link when a chip's sources are dropped — is caught. Default matrix still covers all-chips-ON.

Verification

All configs: build + ctest green (fresh configure each)
Cross-generation include hygiene: grep jaguar3 src/jaguar1 / grep jaguar1 src/jaguar3 both empty
Hardware regression benchmark across the bench DUTs (results in a comment below)

🤖 Generated with Claude Code

Mirror the src/jaguar3/ layout: move the 12 Jaguar1-only module pairs (RtlJaguarDevice, HalModule, RadioManagementModule, EepromManager, FirmwareManager, Iqk8812a, Iqk8814a, PowerTracking8812a, PhydmWatchdog, PhyTableLoader, FrameParser, BbDbgportReader) into src/jaguar1/. Decouple the two generations — neither #includes the other's headers now (only the WiFiDriver factory references both). The shared symbols jaguar3 used from Jaguar1 headers are extracted into neutral headers in src/: - RateDefinitions.h (enum MGN_RATE) - RxPacket.h (Packet / rx_pkt_attrib / RX_PACKET_TYPE) - TxDescBits.h (SET_BITS_TO_LE_4BYTE + LE typedefs/helpers) Make the shared RtlUsbAdapter generation-agnostic: drop infinite_read() (which built the Jaguar1 FrameParser) — the RX loop now reads via the existing generation-neutral bulk_read_raw() and parses in RtlJaguarDevice::read_frames() (Jaguar3 parses via FrameParserJaguar3). No behavior change. Build green all targets; ctest passes; grep confirms no cross-generation #includes. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Let users build only the chip drivers they need. Four options, all default ON (a plain `cmake -S . -B build` is unchanged): DEVOURER_JAGUAR1, DEVOURER_8814 (requires JAGUAR1), DEVOURER_JAGUAR3_8822C, DEVOURER_JAGUAR3_8822E. Invalid combos (none selected; 8814 without jaguar1) fail configure with FATAL_ERROR. The single source list becomes a generation-agnostic core add_library plus per-group target_sources() under if(DEVOURER_*), each exporting a PUBLIC DEVOURER_HAVE_* define so demos see the selection. Sites that reference a dropped group's symbols are guarded with #if defined(DEVOURER_HAVE_*): - factory dispatch (WiFiDriver.cpp) — returns nullptr + logs when a plugged chip's support isn't built; demos null-check and exit cleanly - Firmware.h 8814 fw blob; HalModule 8814 phy-table applies + card-enable flow; RadioManagementModule Iqk8814a member/ctor/calibrate - jaguar3 dispatchers: HalmacJaguar3Fw (per-variant fw), Phy8822cTables / Halrf8822c (per-variant tables + calibration bodies, shells kept), RadioManagementJaguar3 8822e power-by-rate - demo TXAGC/thermal/dbgport/fast-retune downcasts to RtlJaguarDevice CI: build-configs matrix (jaguar1-only, jaguar1+8814, 8822c-only, 8822e-only, jaguar3-only) + reject-bad-configs (the two FATAL cases). 8812AU-only WiFiDriverDemo drops from 2.58 MB to 1.03 MB. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…tions Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

One adapter injects the canonical beacon while each target receives on the same channel — validates RX read+parse + factory dispatch per chip without the kernel driver or ambient traffic. Used to confirm the src/jaguar1 split broke no chip's RX. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

josephnef · 2026-07-01T16:45:49Z

Hardware validation (bench, all-on build)

Re-ran the bench across every plugged DUT — both generations — to confirm the refactor is behavior-neutral. The all-on binary compiles the same code as before (every DEVOURER_HAVE_* defined), so this is a regression check on factory dispatch + init + RX/TX per chip.

TX (tests/bench_init.py, exec → first bulk-OUT) — all pass:

Chip	Generation	TX init
RTL8812AU	Jaguar1	✅
RTL8814AU	Jaguar1 (4T4R)	✅
RTL8821AU	Jaguar1	✅
RTL8812CU (c812)	Jaguar3 rtl8822c	✅
RTL8812EU (a81a)	Jaguar3 rtl8822e	✅

RX (controlled beacon inject → receive, tests/refactor_rx_check.sh) — all pass. Every DUT's factory dispatch selects the right HAL, init completes (monitor RX config + IQK), and the read+parse path delivers frames:

Chip	RX result
RTL8812AU	✅ ch6 (ambient)
RTL8821AU	✅ ch6 (ambient)
RTL8812EU (a81a)	✅ ch6 (58 canonical-beacon hits)
RTL8814AU	✅ ch6 (43 hits)
RTL8812CU (c812)	✅ ch36 (68 hits) — no-frame on ch6, a 2.4 GHz band quirk; rtl8822c's validated band is 5 GHz, and its RX path is shared with a81a which passes on ch6

No regression: factory dispatch, bring-up, TX, and RX all work on every chip across both generations.

josephnef · 2026-07-01T17:08:16Z

Correction + rtl8822c A/B (master vs branch)

My earlier comment leaned on beacon injection and hand-waved the rtl8822c ch6 RX miss. Redone properly with tests/bench_init.py (ambient RX, no injection), A/B against master on the identical chip/channel to isolate whether the refactor caused it:

build	RTL8812CU (c812) RX ch6	c812 RX ch36 (5 GHz)
master (pre-refactor, `f542b06`)	0/2	—
this branch	1/2	400 frames captured

master receives nothing on ch6 either (0/2); the branch is equal-or-better (1/2), and pulls 400 frames on ch36. rtl8822c did not degrade — its weak 2.4 GHz/ch6 reception is pre-existing (marginal ambient RX on its non-primary band), not introduced by the split. The all-on binary compiles byte-identical code to master, so this is expected.

TX init (bench_init, exec → first bulk-OUT) still passes on all five DUTs: 8812AU, 8814AU, 8821AU, rtl8822c, rtl8822e.

basic_types.h's cpu_to_le / le_to_cpu macros expand to __u16/__u32, which before the src/jaguar1 split reached every TU transitively through FrameParser.h. Post-split a Jaguar1 TU can include basic_types.h without the TX-descriptor header, so define the two typedefs at the typedef home (drv_types.h, included by basic_types.h). Fixes the all-on / jaguar1 CI build. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Guard against local lab notes and Claude Code state being committed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

josephnef and others added 5 commits July 1, 2026 19:02

docs: README project layout for src/jaguar1 split + per-chip build op…

4e805c0

…tions Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs: CLAUDE.md src/jaguar1 layout + per-chip build options

4ffff33

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

josephnef mentioned this pull request Jul 1, 2026

RTL8812CU (rtl8822c) RX marginal on 2.4 GHz channel 6 #126

Closed

josephnef and others added 2 commits July 1, 2026 20:15

chore: gitignore local files (INVENTORY.md, .claude/)

7870d9d

Guard against local lab notes and Claude Code state being committed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

josephnef force-pushed the refactor-split-jaguar1 branch from 5d1c0eb to 7870d9d Compare July 1, 2026 17:19

josephnef merged commit 55f0649 into master Jul 1, 2026
12 checks passed

josephnef deleted the refactor-split-jaguar1 branch July 1, 2026 17:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Split Jaguar1 into src/jaguar1/ + compile-time per-chip selection#125

Split Jaguar1 into src/jaguar1/ + compile-time per-chip selection#125
josephnef merged 7 commits into
masterfrom
refactor-split-jaguar1

josephnef commented Jul 1, 2026

Uh oh!

josephnef commented Jul 1, 2026

Uh oh!

josephnef commented Jul 1, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

option	chips
`DEVOURER_JAGUAR1`	8812AU / 8811AU / 8821AU
`DEVOURER_8814`	8814AU (requires `DEVOURER_JAGUAR1`)
`DEVOURER_JAGUAR3_8822C`	8812CU / 8822CU
`DEVOURER_JAGUAR3_8822E`	8812EU / 8822EU

Uh oh!

Uh oh!

Conversation

josephnef commented Jul 1, 2026

What

Size win

CI

Verification

Uh oh!

josephnef commented Jul 1, 2026

Hardware validation (bench, all-on build)

Uh oh!

josephnef commented Jul 1, 2026

Correction + rtl8822c A/B (master vs branch)

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant